home *** CD-ROM | disk | FTP | other *** search
/ Atari Mega Archive 1 / Atari Mega Archive - Volume 1.iso / language / sozo2 / scdoc20.lzh / SZADB.DOC < prev   
Text File  |  1991-03-03  |  12KB  |  347 lines
  1.  
  2. NAME
  3.  
  4.     szadb - Sozobon debugger
  5.  
  6. USAGE
  7.  
  8.     szadb  program
  9.  
  10. SUMMARY
  11.  
  12. Szadb is a machine language debugger with symbols which is similar
  13. to the old UNIX 'adb' command.  Szadb is used to control and monitor
  14. another program.  This program is loaded into memory and relocated
  15. when szadb is first started.  Commands to szadb allow the user to
  16. examine and modify memory and machine registers, single step and set
  17. breakpoints.
  18.  
  19.  
  20. WINDOWS
  21.  
  22. Szadb uses its own window or screen.  Thus commands and output will
  23. not interfere with the program's window.  In fact, szadb does output
  24. without using the BIOS so as not to confuse the program's cursor.
  25.  
  26. Use <cntl-w> to view the program's screen when you are in the szadb
  27. window.  Type another character to get back.
  28.  
  29.  
  30. ONLINE HELP
  31.  
  32. A summary of this manual is available by typing the 'help' key.  Use 'q'
  33. to get back to the szadb prompt.  Typing any other key will advance to the
  34. next help screen.
  35.  
  36. People in other countries are encouraged to come up with versions of szadb
  37. with the messages in their language.  You should only have to change the one
  38. file "lang.h".
  39.  
  40.  
  41. SYNTAX
  42.  
  43. In the following description of commands, certain syntactic abbreviations
  44. are used.
  45.  
  46.     {expr}   - any valid expression consisting of numbers, symbols and
  47.            operators.  See the section on EXPRESSIONS
  48.        ,{count}  - a repeat count for the command.  Can be any expression
  49.     {format} - a string of characters which specifies how values are printed
  50.            See the section on FORMATS
  51.     {args}     - The arguments or parameters to be passed to the program
  52.     {value}  - an additional expression used by the command
  53.  
  54.  
  55. FORMAT OF COMMANDS
  56.  
  57. The general format for command X is
  58.  
  59.     {expr},{count}X            for most commands
  60. or    {expr},{count}X{format}        for / or ? or =
  61. or    {expr},{count}X{args}        for :c or :s
  62. or    {expr},{count}X{value}        for /w or /W
  63.  
  64. Spaces and tabs can be input to improve readability.  They are always
  65. ignored.
  66.  
  67. All fields are optional.  If {count} is missing, we do the command once.
  68. If {format} is missing we re-use the last {format}.  If {args} are missing,
  69. no parameters are passed.  If {values} are missing, nothing is written.
  70.  
  71. If {expr} is missing, we use the value of DOT.  DOT is set to the PC after
  72. we single step or hit a breakpoint.  DOT is set to {expr} by most commands.
  73. DOT is set to the next address after locations that were printed by
  74. the / or ? command.
  75.  
  76. If the command is missing, we use the last command.  Thus an empty line
  77. repeats the last command with DOT for the {expr} and 1 for the {count}
  78. (and {format} the same as before).
  79.  
  80.  
  81. THE ':' GROUP
  82.  
  83.     :s or :S
  84.  
  85.     This command is used to single step the program.  It will use the
  86.     trace bit of the 68000 to force a trap after one instruction.
  87.     We do not switch to the program window for single stepping.
  88.  
  89.     :c or :C
  90.  
  91.     This command is used to continue the program.  We will switch to
  92.     the program window and run at full speed until a breakpoint is
  93.     hit, a trap occurs or the program exits. 
  94.  
  95.     The upper case versions of each command print all the machine
  96.     registers after running the program.
  97.  
  98.     The first :c or :s can be followed by {args} which specify the
  99.     parameters to be passed to the program.
  100.  
  101.     If an {expr} field is given to the :c or :s, the PC is set to
  102.     that value.  This should be used with care!
  103.  
  104.     :b  -  set a breakpoint at {expr}
  105.     :d  -  delete the breakpoint at {expr}
  106.  
  107. Note that the only way to re-start the program is to exit szadb and start
  108. over.
  109.  
  110. THE '$' GROUP
  111.  
  112.     $q    - quit szadb
  113.     $r    - print all register values
  114.     $e    - print all external symbols and their values
  115.     $o    - use octal numbers
  116.     $x    - use hex numbers
  117.     $d    - use decimal numbers
  118.       $s    - set the maximum symbol offset to {expr}
  119.           When address are printed by szadb, they are printed as
  120.           symbol+offset if offset is <= to this value
  121.     $b    - print all breakpoints
  122.     $c    - print a stack backtrace
  123.     $C    - print a stack backtrace with arguments
  124.           If szadb cannot determine the number of arguments
  125.           (because there were none or because the optimizer was used),
  126.           it prints the location on the stack where they might be
  127.     $p    - print the basepage of the program
  128.  
  129.  
  130. THE '/' or '?' GROUP
  131.  
  132. UNIX adb uses '?' to examine a program file and '/' to look at running
  133. process's memory.  Since szadb only looks at memory, either can be used.
  134. We recommend using '/' since later versions of szadb may use '?' for files.
  135.  
  136.     /
  137.  
  138.     Print values from memory according to a format.  See FORMATS.
  139.     {expr} gives the starting address to fetch values from.
  140.     If there is more than one format character, we increment the
  141.     address used by the size of the value printed.
  142.  
  143.     /w    - Write a 2-byte value to memory at address {expr}
  144.     /W    - Write a 4-byte value to memory at address {expr}
  145.  
  146. THE '=' COMMAND
  147.  
  148.     =
  149.  
  150.     Print the value of {expr} according to a format.  See FORMATS.
  151.     If there is more than one format character, we print the same
  152.     value each time.
  153.  
  154. THE '>' GROUP
  155.  
  156. Register values can be changed using '>' followed by the register name.
  157. This sets that register to the value of {expr}.  See REGISTER NAMES
  158.  
  159.  
  160. FORMATS
  161.  
  162. Formats are similar to printf() format strings.  They specify the way
  163. values are printed.  However, since we almost always want to print a
  164. value and not some literal string, the '%' before each format is missing.
  165. Also, we usually use upper case for long values instead of a leading 'l'.
  166. Thus %d%lx%o becomes dXo.
  167.  
  168.     d  - print 2-bytes as decimal
  169.     D  - print 4-bytes as decimal
  170.     x  - print 2-bytes as hex
  171.     X  - print 4-bytes as hex
  172.     o  - print 2-bytes as octal
  173.     O  - print 4-bytes as octal
  174.     c  - print a single character
  175.     b  - print 1-byte as octal
  176.     s  - print a string
  177.  
  178. In addition, we add the following non-printf-like formats:
  179.  
  180.     i  - print a single machine language instruction
  181.     S  - print a string with '.' for special characters
  182.     p  - print the current value of DOT as a symbol plus offset
  183.     a  - same as p except also print a ':' and tab
  184.     r  - print a space
  185.     n  - print a newline
  186.  "string"  - print a literal string
  187.     +  - increment DOT (nothing printed)
  188.     -  - decrement DOT (nothing printed)
  189.     ^  - backup DOT by the last size printed
  190.  
  191. Formats can also be preceeded by a decimal number.  This number is
  192. usually the repeat count for the next format.  Thus instead of saying
  193. main/iiiiXXXXXX you can say main/4i6X
  194.  
  195. The 't' format is always preceed by a number.  This format advances to
  196. the next tab stop which a multiple of that number.
  197.  
  198.  
  199. EXPRESSIONS
  200.  
  201.     Expressions are a lot like C expressions.  They include numbers
  202. and symbols with unary and binary operators.  Expressions are always
  203. evaluated using long (4-byte) arithmetic.  Parenthesis can be used for
  204. grouping.  There is no precedence among binary operators - evaluation is
  205. strictly left to right.
  206.  
  207.     NUMBERS
  208.  
  209.     Numbers can be entered in any base.  A base is specified using one
  210. of the following prefixes:
  211.  
  212.     0x - hex
  213.     0t - decimal
  214.     0o - octal
  215.  
  216.     If there is no such prefix, the default base will be used.  The
  217. default base when you start szadb is hex.  Use a leading 0 if you need
  218. to enter a hex number which starts with a letter.
  219.  
  220.     SYMBOLS
  221.  
  222.     If your program has a symbol table, these symbol names can be
  223. used in expressions.  The value of a symbol is the address of that
  224. variable or function.  Although the C compiler adds a leading '_' to
  225. all symbols, the symbol name will be found with or without the '_'.
  226.  
  227.     OTHER VALUES
  228.  
  229.     Character literals can be entered by enclosing one to four
  230. characters in single quotes.  Multi-character literals put the first
  231. character in the highest byte.
  232.  
  233.     The value of DOT can be used in an expression by typing "."
  234.  
  235.     Use "&" to represent the last typed {expr} field.  (DOT
  236. changes when you print with / or ?.  "&" does not.)
  237.  
  238.     UNARY OPERATORS
  239.  
  240.     -   unary minus (2-s complement)
  241.     ~   bitwise complement (1-s complement)
  242.     *   fetch of 4 bytes from an address
  243.     @   fetch of 2 bytes from an address
  244.  
  245.     BINARY OPERATORS
  246.  
  247.     +   addition
  248.     -   subtraction
  249.     *   multiplication
  250.     %   division (NOT '/' !)
  251.     &   bitwise and
  252.     |   bitwise or
  253.